home *** CD-ROM | disk | FTP | other *** search
/ Aminet 8 / Aminet 8 (1995)(GTI - Schatztruhe)[!][Oct 1995].iso / Aminet / dev / e / UsefulV2.lha / UsefulV2.readme
Text File  |  1995-09-04  |  6KB  |  151 lines
  1. Short: JRH's useful E modules (version 2)
  2. Type: dev/e
  3. Author: jason@fsel.com (Jason R. Hulance)
  4. Uploader: jason@fsel.com (Jason R. Hulance)
  5.  
  6. JRH's Useful Modules (Version 2)
  7. ================================
  8.  
  9. These modules are Copyright (C) 1995, Jason R. Hulance.
  10.  
  11. You are free to use these modules in your programs, whether they are freeware
  12. or commercial.  However, if you want to distribute any of this archive you
  13. must include it all, unmodified, together with this file.
  14.  
  15. Contents
  16. --------
  17.  
  18. [This version is mainly a bug-fix: the eCodeXXX() routines did not flush the
  19. CPU caches so could fail on a 68040, and the resource modules have been
  20. simplified thanks to a bug-fixed EC v3.2a.]
  21.  
  22. Various modules:
  23.  
  24.   ecode.m:
  25.     PROC eCode(func)
  26.     PROC eCodePreserve(func)
  27.     PROC eCodeTask(func)
  28.     PROC eCodeASLHook(func)
  29.     PROC eCodeCxCustom(func)
  30.     PROC eCodeCollision(func)
  31.     PROC eCodeIntHandler(func)
  32.     PROC eCodeIntServer(func)
  33.     PROC eCodeSoftInt(func)
  34.     PROC eCodeSwapArgs(func)
  35.     PROC eCodeDispose(addr)
  36.  
  37.   split.m:
  38.     PROC argSplit(str=0)
  39.  
  40.  
  41. Amiga E does not support Resources (at least, not up to v3.1a, anyway).
  42. These modules rectify this.
  43.  
  44.   battclock.m:
  45.     DEF battclockbase
  46.     PROC readBattClock()
  47.     PROC resetBattClock()
  48.     PROC writeBattClock(time)
  49.  
  50.   battmem.m:
  51.     DEF battmembase
  52.     PROC obtainBattSemaphore()
  53.     PROC readBattMem(buffer,offset,length)
  54.     PROC releaseBattSemaphore()
  55.     PROC writeBattMem(buffer,offset,length)
  56.  
  57.   cia.m:
  58.     PROC ableICR(resource,mask)
  59.     PROC addICRVector(resource,iCRBit,interrupt)
  60.     PROC remICRVector(resource,iCRBit,interrupt)
  61.     PROC setICR(resource,mask)
  62.  
  63.   disk.m:
  64.     DEF diskbase
  65.     PROC allocUnit(unitNum)
  66.     PROC freeUnit(unitNum)
  67.     PROC getUnit(unitPointer)
  68.     PROC getUnitID(unitNum)
  69.     PROC giveUnit()
  70.     PROC readUnitID(unitNum)
  71.  
  72.   misc.m:
  73.     DEF miscbase
  74.     PROC allocMiscResource(unitNum,name)
  75.     PROC freeMiscResource(unitNum)
  76.  
  77.   potgo.m:
  78.     DEF potgobase
  79.     PROC allocPotBits(bits)
  80.     PROC freePotBits(bits)
  81.     PROC writePotgo(word,mask)
  82.  
  83.  
  84. Documentation
  85. -------------
  86.  
  87. The standard documentation on the Resource functions suffices for the
  88. Resource modules.  All the other functions (eCodeXXX and split) return NIL
  89. if an error occurred, which is normally "out of memory".
  90.  
  91.   ecode.m:
  92.     o   eCode() takes the address of an E function (or a label) and wraps it
  93.       so that it can be called from other tasks/processes and still access
  94.       the global variables of the main program.  This function was created
  95.       for use with createTask(), but has other uses.
  96.     o   eCodePreserve() is similar, but it also protects the function by
  97.       preserving the non-scratch registers on the stack.  This means the
  98.       function can retrieve (and change) registers D2-D7/A2-A6 as local
  99.       variables.  For instance,
  100.         PROC fun(a6,a5,a4,a3,a2,d7,d6,d5,d4,d3,d2) IS d2:=d3+a3
  101.       will have the effect of changing register D2 (and D0) when the
  102.       function returns.  Note: you do not need to specify all registers,
  103.       just the suffix of the above that you are actually interested in.
  104.         PROC fun(a3,a2,d7,d6,d5,d4,d3,d2) IS d2:=d3+a3
  105.       would have done...
  106.     o   eCodeTask() is just eCode() with a more suggestive name.
  107.     o   eCodeASLHook() takes the address of an E function (or a label) and
  108.       returns something usable as an ASL hook function (nothing to do with
  109.       the utility library hooks, more's the pity).
  110.     o   eCodeCxCustom() does the same for CX custom functions.
  111.     o   eCodeCollision() does the same for GEL collision functions.
  112.     o   eCodeIntHandler() is for interrupt handlers: you get A1 and D1 as
  113.       arguments (in that order) to your function.  (A1 is the data element
  114.       of your interrupt, and D1 contains the interrupt flags.)
  115.     o   eCodeIntServer() is for interrupt servers: you get A1 (the data
  116.       element of your interrupt) as an argument.
  117.     o   eCodeSoftInt() is the same, but for software interrupts.
  118.     o   eCodeSwapArgs() is like eCode() except it swaps the order of two
  119.       arguments on the stack.  This means the E function can have its
  120.       arguments in the same order as a similar C function.  For example,
  121.       you can use this instead of eCodeCollision() if your collision code is
  122.       simple (i.e., doesn't use PrintF() and the like).
  123.     o   eCodeDispose() is passed the result of the one of the above
  124.       functions, and will to dispose the memory used by the special wrapper.
  125.       You will rarely need to use this, as the memory will be freed
  126.       automatically at the end of the program.
  127.     o   eCodeASLHook(), eCodeCxCustom(), eCodeIntHandler(), eCodeIntServer()
  128.       and eCodeSoftInt() all use their own private scratch area to preserve
  129.       registers, thus saving crucial stack space.  This has the disadvantage
  130.       of making the code non-reentrant, so if you need to use the same
  131.       function as multiple interrupt servers you must use eCodeIntServer()
  132.       multiple times.  Apart from that they should be OK, since they do
  133.       not get called from multiple tasks.  (If you find this a problem then
  134.       you can use eCodePreserve()...)
  135.     o   eCodePreserve() uses a big bit of STACK to store registers, so be
  136.       careful...
  137.  
  138.   split.m:
  139.     o   argSplit(str=NIL) splits a string of arguments like "arg" (which is
  140.       the default), handling quoted arguments correctly.  The result is an
  141.       E-list of strings, or NIL if an error occurred.  The list is also
  142.       NIL-terminated so you have a choice of ways to manipulate it.  The
  143.       string passed to this function (or "arg" by default) is *altered* by
  144.       this function, so you shouldn't try using it directly.  You can
  145.       DisposeLink() the resulting list if you want to free it before the end
  146.       of the program.  (You are also responsible for freeing the string when
  147.       you are done with it, unless it was the default "arg", of course.)
  148.  
  149. The main reason for the creation of these modules was my translations of the
  150. RKRM examples.  These provide many examples of the use of these functions.
  151.